---
title: Univer Docs API
---

Univer Docs 提供专业级文档排版能力，相关概念会尽可能与 Microsoft Word 保持一致。

## 操作文档

命令系统中 `unitId` 对应的是文档的唯一标识，文档不存在 `subUnitId`。

文档的文本内容存储在 `body.dataStream` 字符串中，此字符串不包含样式信息。

样式信息单独存储在另外的数据结构中，并通过下标索引与文本内容关联。

对于换行、分页、章节、段落、表格等元素， 在文本内容中使用不同的特殊字符来标记，这些特殊字符在渲染时被转换为对应的元素。

<Callout>
  想要进一步了解文档的数据结构设计吗？推荐阅读[《Univer 文档架构及模块设计》](/blog/univer-doc-architecture) 和[《Univer 文档排版设计初探》](/blog/doc-typesetting-design)。
</Callout>

### 创建文档

`univer.createUnit` 方法用于创建一个新的文档实例。当第一个参数的值为 `UniverInstanceType.UNIVER_DOC` 时，表示创建一个文档实例。

此时第二个参数是一个可选的 `DocumentDataModel` 对象，包含了文档的初始数据。如果传入 `{}`，则创建一个空文档。

创建成功后返回一个 `DocumentDataModel` 对象，包含了文档的唯一标识 `unitId` 和其他相关信息。

```typescript
// [!code word:data]
univer.createUnit(UniverInstanceType.UNIVER_DOC, data)
```

### 获取文档 unitId

```typescript
const doc = univerAPI.getActiveDocument()
const unitId = doc?.getId()
```

### 获取文档数据

```typescript
const doc = univerAPI.getActiveDocument()
const saveData = doc.getSnapshot()
```

### 销毁文档

当我们不再需要文档时，可以调用 Univer 实例的 `dispose` 方法来销毁实例。

```typescript
univer.dispose()
```

## 操作文本

对富文本区域的文本元素进行操作

### 插入文本

将指定的文本添加到此文本区域的末尾。

```typescript
const doc = univerAPI.getActiveDocument()
doc?.appendText('Univer')
```

### 删除文本

删除光标前的字符

```typescript
univerAPI.executeCommand('doc.command.delete-left')
```

删除光标后的字符

```typescript
univerAPI.executeCommand('doc.command.delete-right')
```

## 修改样式

为选中的文本设置字体色

```typescript
univerAPI.executeCommand('doc.command.set-inline-format-text-color', { value: '#ff0000' })
```

## 插入分页符

`\f` 为分页符，用于在文档中插入分页符。

```typescript
const doc = univerAPI.getActiveDocument()
doc?.appendText('\f')
```

## 插入列表

给光标所在段落添加一个无序列表，重复调用则取消无序列表

```typescript
univerAPI.executeCommand('doc.command.list-operation', { listType: 'BULLET_LIST' })
```

给光标所在段落添加一个有序列表，重复调用则取消有序列表

```typescript
univerAPI.executeCommand('doc.command.list-operation', { listType: 'ORDER_LIST' })
```
